\n The instrument library is a tool that enables predicate definitions or all\n calls to a specific predicate to be annotated with user-defined predicates.\n These instrumentation predicates are free to perform such actions as collect\n program statistics or write debugging data to a stream during program\n execution. Additionally, the instrumentation can be inserted and removed\n dynamically as the program executes.\n
\nThe usage is as follows:\n
\n ?- lib(instrument).\n\n
\n ?- instrument:instrument(my_program, Templates).\n\n
\n ?- my_query(X,Y,Z).\n\n
\n ?- instrument:results(my_program).\n\n
\n The following is an example of very basic use of the tool.\n Consider instrumenting a simple path finding program saved in a\n file called 'instrument_example.ecl.\n
\n list_member(X, [X | _Tail]).\n list_member(X, [_ | Tail]):-\n list_member(X, Tail).\n \n all_edges(Graph, Source, Outgoing):-\n findall((Source-Next),list_member((Source-Next), Graph), Outgoing).\n \n path(_Graph, Source, Source, []).\n path(Graph, Source, Sink, [(Source-Next) | Path]):-\n all_edges(Graph, Source, Outgoing),\n list_member((Source-Next), Outgoing),\n path(Graph, Next, Sink, Path).\n \n test(Path):-\n path([1-2, 1-3, 2-4, 3-4, 4-5, 4-6, 5-7, 5-8, 6-7,\n 1-8, 8-9, 8-10, 9-10, 9-11, 10-11],\n 1,\n 7,\n Path).\n\n The simplest way to instrument your code is to insert predicates around\n every call in the source. The following code demonstrates how to\n print the CPU time before and after every predicate call:\n
\n get_time(Cpu):-\n statistics(times, [Cpu, _Sys, _Real]).\n \n time_point:-\n get_time(T),\n writeln(error, T).\n \n go:-\n File = instrument_example,\n GlobalTemplate = itemplate{subgoal_start:time_point/0,\n subgoal_end:time_point/0},\n instrument(File, GlobalTemplate),\n test(Path).\n \n Note the same predicate time_point/0 is specified before and\n after goal calls. If we wished to instrument all calls except those\n to list_member/2, the following call to instrument/2 is\n made:\n \n instrument(File, GlobalTemplate - [list_member/2])\n\n In general any number of goals may be specified in this 'exclusion list'.\n
\n The following code demonstrates alternative instrumentation\n for this excluded predicate:\n
\n :-lib(instrument).\n\n :-export time_point/0, special_point/0.\n\n get_time(Cpu):-\n statistics(times,[Cpu, _Sys, _Real]). \n\n time_point:-\n get_time(T),\n writeln(error, T).\n\n special_point:-\n writeln(error, 'start, end, redo or fail').\n\n go:-\n File = instrument_example,\n GlobalTemplate = itemplate{subgoal_start:time_point/0,\n subgoal_end:time_point/0},\n SpecialTemplate = itemplate{call_start:special_point/0,\n call_end:special_point/0,\n call_fail:special_point/0\n call_redo:special_point/0},\n instrument(File,[GlobalTemplate - [list_member/2],\n (list_member/2) = SpecialTemplate]),\n test(Path).\n \n Notice how the special_point/0 predicate is assigned to the\n call_start, call_end, call_fail and \n call_redo points in this example. This ensures that the \n special_point predicate is called if list_member/2 \n fails, or if resatisfiable, executed at the redo.\n \n Using arity-1 predicates (i.e. one argument predicates)\n unique identification of the callsite can be obtained:\n
\n :-lib(instrument).\n\n get_time(Cpu):-\n statistics(times, [Cpu, _Sys, _Real]). \n\n time_point(CallSite):-\n get_time(T),\n writeln(error,['Time', T, 'at callsite', CallSite]).\n\n go:-\n File = instrument_example,\n GlobalTemplate = itemplate{subgoal_start:time_point/1,\n subgoal_end:time_point/1},\n instrument(File, GlobalTemplate),\n test(Path).\n \n \n By supplying a predicate to the result field of a template \n one can specify terms to be printed within a copy of the source code.\n Using this feature along with the utility predicates \n get_callsite_data/2 and set_callsite_data/2 \n one can create quite varied and useful output.\n
\n :-lib(instrument).\n\n get_time(Cpu):-\n statistics(times, [Cpu, _Sys, _Real]). \n\n time_point(CallSite):-\n get_time(T),\n set_callsite_data(CallSite, T).\n\n result(CallSite, _Type, _Module, Goal, NewGoal):-\n get_callsite_data(CallSite, Time),\n NewGoal='instrument:point_before'(Time, Goal).\n go:-\n File = instrument_example,\n GlobalTemplate = itemplate{subgoal_start:time_point/1,\n result:result/5},\n instrument(File, GlobalTemplate),\n test(Path),\n file_result(File).\n \n No data is printed during the running of the test(Path) call, \n but the file_result(File) call causes the source code to be \n emitted (color coded) with the given callsite data embedded.\n")).
:- comment(struct(itemplate), [summary : " The template used to guide predicate instrumentation", fields : [clause_start : "PredSpec of maximum arity two, the atom 'inherit', or variable", clause_end : "PredSpec of maximum arity two, the atom 'inherit', or variable", clause_fail : "PredSpec of maximum arity two, the atom 'inherit', or variable", clause_redo : "PredSpec of maximum arity two, the atom 'inherit', or variable", block_start : "PredSpec of maximum arity two, the atom 'inherit', or variable", block_end : "PredSpec of maximum arity two, the atom 'inherit', or variable", block_fail : "PredSpec of maximum arity two, the atom 'inherit', or variable", block_redo : "PredSpec of maximum arity two, the atom 'inherit', or variable", subgoal_start : "PredSpec of maximum arity two, the atom 'inherit', or variable", subgoal_end : "PredSpec of maximum arity two, the atom 'inherit', or variable", subgoal_fail : "PredSpec of maximum arity two, the atom 'inherit', or variable", subgoal_redo : "PredSpec of maximum arity two, the atom 'inherit', or variable", call_start : "PredSpec of maximum arity two, the atom 'inherit', or variable", call_end : "PredSpec of maximum arity two, the atom 'inherit', or variable", call_fail : "PredSpec of maximum arity two, the atom 'inherit', or variable", call_redo : "PredSpec of maximum arity two, the atom 'inherit', or variable", fact : "PredSpec of maximum arity one, the atom 'inherit', or variable", inbetween : "PredSpec of maximum arity two, the atom 'inherit', or variable", result : "PredSpec of maximum arity five, the atom 'inherit', or variable", meta_args : "List of itemplate or variable", exclude : "List of PredSpec, the atom 'inherit', or variable", code_weaver : "PredSpec of maximum arity six, the atom 'inherit', or variable", asserted : "Specific atom, the atom 'inherit' or variable", module_scope : "Atomic module name, the atom 'inherit' or variable", file_local : "Specific atom, the atom 'inherit' or variable", goal_expansion : "Specific atom, the atom 'inherit' or variable"], see_also : [erase_all_templates / 0, get_callsite_data / 2, instrument / 2, instrument / 3, instrument_control / 2, library(instrument), module_callsites / 2, module_result / 0, set_callsite_data / 2, defined_modules / 2], desc : html("\n The itemplate structure serves as a specification that \n determines how predicate definitions and calls to predicates are instrumented.\n
\n An itemplate is associated with a predicate whose definition or \n invocations are to be instrumented. This association is specified as an \n argument to instrument:instrument/2 or instrument:instrument/3 \n and is of the form: PredSpec = itemplate{...}.\n
\n PredSpec is of the form Module:Functor/Arity. \n If the module qualifier is omitted, then PredSpec is assumed to \n be a predicate defined within the calling module context in which \n instrument/2 was invoked. The definition context for a module \n can be wildcarded by specifying the module qualifier as the atom \n every_module or by setting the itemplate module_scope \n field to every_module.\n
\n This has two effects:\n
\n When determining whether a predicate is to be instrumented, a template is \n sought which matches the module qualified PredSpec, first using \n the named module (or current module if unqualified) and then using \n every_module as the module qualifier.\n
\n Within the template, predicate specifications supplied to its fields \n determine how predicate instrumentation and invocation proceeds. \n The template specifies the following instrumentation points:\n
clause_start\n
clause_end\n
clause_fail\n
clause_redo\n
block_start\n
block_end\n
block_fail\n
block_redo\n
subgoal_start\n
subgoal_end\n
subgoal_fail\n
subgoal_redo\n
call_start\n
call_end\n
call_fail\n
call_redo\n
fact\n
inbetween\n
\n The default value for the instrumentation predicates is that none are \n defined and so no instrumentation is performed. This is equivalent to \n setting the field values explicitly to free variables.\n
\n The instrumentation predicates must be defined with one of the following \n signatures:\n
\n It is anticipated that the callsite identifier be used for executing \n callsite specific code or storing data pertinent to the callsite in a \n non-logical store keyed by callsite identifier - \n set_callsite_data/2 and get_callsite_data/2 are provided \n for exactly this purpose.\n
\n The auxiliary variable passed as argument two to instrumentation \n predicates is provided for convenience for capturing 'delta' measurements \n between the start, end and fail instrumentation points. The variable is a \n logical variable and while the value passed to the end or fail predicate \n is guaranteed to be the value bound by the start predicate, backtracking \n past the start predicate results in the unbinding of the variable. If the \n captured delta should be retained beyond backtracking then it should be \n placed in the callsite's non-logical store using set_callsite_data/2.\n
\n The maximum arity of the fact and inbetween point predicates is one - \n only the callsite identifier is passed, there is no benefit in passing an \n auxiliary variable.\n
\n The result instrumentation predicate provides a mechanism for \n pretty-printing the annotated source code with the instrumentation results \n gathered during execution. By executing instrument:module_result/0\n or instrument:file_result/1 the predicate specified for result \n instrumentation within the template is invoked as each of the \n instrumentation points are encountered for pretty-printing.\n
\n The result instrumentation predicate must be defined with one of the \n following signatures:\n
\n The meta_args field of the itemplate structure is \n applicable only to templates associated with predicates that are \n meta-predicates. When applicable, meta_args is a list of \n itemplate. Each element in the list is a template for the \n corresponding argument of the meta-predicate. The template defined \n instrumentation points are applied to the code found inside the \n meta-predicate at this argument position. For example: \n
findall/3 = itemplate{..., meta_args:[_, ITemplateArg2, _]...} \n is an itemplate specification describing the instrumentation \n of the meta-predicate findall/3. Argument one and three undergo \n no instrumentation (denoted by free variables) and argument two is \n instrumented according to ITemplateArg2.\n \n Within the meta-predicate argument itemplate fields may be \n specified as being inherit-ed. When such a field is specified \n as inherited it is set to the corresponding value of the template used in \n instrumenting the definition of the predicate in which the call to the \n meta-predicate resides. \n
\n The exclude field of the itemplate contains a list of \n predicate specifications. Any occurrence of such a predicate as a call \n or subgoal is excluded from application of the instrumentation specified \n by the enclosing template. The main use of exclusion is in preventing \n instrumentation application to recursive predicates or built-ins.\n
\n The code_weaver field of the itemplate specifies a \n predicate of arity six that is a compile-time callback allowing arbitrary \n user code to be woven into the code currently undergoing compilation. The \n weaving of user code is performed before the insertion of instrumentation \n predicates. The arguments of the predicate are as follows:\n
\n The remaining fields of the itemplate structure specify the \n options:\n
\n The value of asserted may be the atoms: on, off and \n post_compile or a free variable. When a free variable, the \n instrumentation predicates are compiled into the code like any other \n predicates. However, when set to one of the atomic values, the predicates \n are compiled such that they can be inserted and removed at runtime. This \n is done efficiently such that there is negligible overhead on execution.\n
\n The value on specifies that the predicates are initially inserted.\n The value off that they are removed and post_compile \n that they are not inserted until compilation of the whole file has \n completed. The post_compile option is provided so that \n instrumentation predicates inserted into predicate definitions that get \n executed at compile-time do not get executed.\n
\n During execution, the instrumentation predicates can be inserted and \n removed using instrument:instrument_control/2. \n
\n The possible values are an atom representing a module name, the atom \n every_module or a free variable indicating the current module. \n The value is used to determine the module definition context of \n unqualified instrumentation predicates or the predicate associated with \n the template for definition and call instrumentation:\n
\n The unqualified predicate is qualified with the named module.\n
\n The unqualified predicate is qualified with the calling module context \n in which instrument/2 was first invoked.\n
\n The unqualified predicate is qualified with the name of the current \n compilation module.\n
\n Templates persist in a global store between successive calls to \n instrument/2 and instrument/3. If it is undesirable \n for a template to be added to the global store (thus making it available \n for the instrumentation of other files and modules) an itemplate \n may be declared as being applicable to only the file currently being \n instrumented by setting this option to on.\n
\n The search order for an instrumentation template is first in the file \n local store and then in the global store.\n
\n Setting this to off will suppress goal expansion inlining) \n during compilation. This may be necessary when the processed code \n contains predicates that get executed at compile time. \n
")]). :- comment(defined_modules / 2, [summary : "Retrieve the modules defined by a file.", args : ["File" : "Atom or string", "Modules" : "List of atoms"], amode : defined_modules(+, -), fail_if : no, resat : no, see_also : [get_callsite_data / 2, file_callsites / 3, instrument / 2, instrument / 3, library(instrument), set_callsite_data / 2, struct(itemplate), defined_modules / 2], desc : html("
\n It is often necessary to know what modules a file has defined in order \n to operate on module specific data. This predicate can be used to return \n the modules defined by a file which has been compiled with the instrument \n compiler.")]). :- comment(erase_all_templates / 0, [summary : "Erase all instrument template stores.", args : [], fail_if : no, resat : no, desc : html("
\n This predicate erases all itemplate that are persisted in \n the global and file local template stores between successive calls \n to instrument/2 and instrument/3."), see_also : [erase_module_templates / 0, erase_file_templates / 1, instrument / 2, instrument / 3, library(instrument), struct(itemplate), defined_modules / 2]]). :- comment(erase_file_templates / 1, [summary : "Erase the file local instrument template store for a\n specific file.", amode : erase_file_templates(+), args : ["File" : "Atom or string"], fail_if : "No instrumentation templates exist for the file in \n the calling module context.", resat : no, desc : html("
\n This predicate erases all templates associated with the named file \n that was compiled into the the calling module context and persisted \n by (successive) calls to instrument/2 and instrument/3. \n The predicate is a tool and the file local templates of a module other \n than the current calling module context can be erased by invoking \n erase_file_templates(File)@Module."), see_also : [erase_all_templates / 0, erase_module_templates / 0, instrument / 2, instrument / 3, library(instrument), struct(itemplate), defined_modules / 2]]). :- comment(erase_module_templates / 0, [summary : "Erase all instrument template stores for a specific module.", args : [], fail_if : "No instrumentation templates exist for the calling module.", resat : no, desc : html("
\n This predicate erases all templates of the calling module context, \n that are persisted in the global and file local template stores \n between successive calls to instrument/2 and instrument/3. \n The predicate is a tool and the templates of a module other than the \n current calling module context can be erased by invoking \n erase_module_templates@Module. To erase templates \n applicable to all modules, the atom every_module may be \n specified."), see_also : [erase_all_templates / 0, erase_file_templates / 1, instrument / 2, instrument / 3, library(instrument), struct(itemplate), defined_modules / 2]]). :- comment(file_callsites / 3, [summary : "Retrieve start and end callsite identifiers for named file.", args : ["File" : "Atom or string", "StartId" : "Intger", "EndId" : "Integer"], amode : file_callsites(+, ?, ?), fail_if : "StartId or EndId are not the file's starting and \n ending callsite identifiers.", resat : no, see_also : [get_callsite_data / 2, instrument / 2, instrument / 3, library(instrument), module_callsites / 2, set_callsite_data / 2, struct(itemplate), defined_modules / 2], desc : html("
\n Each code instrumentation point within a file is \n uniquely identified by its callsite identifier.\n The callsite identifier is a monotonically increasing \n integer incrementing from the initial value of 0 for a \n new module. \n
\n As additional files are instrumented and \n compiled into a module, the start identifier is \n incremented from the end identifier of the previous file. \n The predicate retrieves the start and end callsite \n identifiers for the file.\n
\n The predicate is a tool and the callsite identifiers \n of a file instrumented in a module other than the current \n calling module context can be retrieved by invoking \n file_callsites(File, StartId, EndId)@Module.")]). :- comment(file_result / 1, [summary : "Pretty-print a file, including any instrumentation results", amode : file_result(+), args : ["File" : "Atom or string"], see_also : [instrument / 2, instrument / 3, file_result / 2, library(instrument), library(pretty_printer), module_result / 0, module_result / 1, struct(itemplate), defined_modules / 2], desc : html("
\n This will pretty-print the specified source file in the calling \n module context, annotated with the result of instrumentation. \n The resulting .html file is placed in a sub-directory called \n instrument', relative to File.\n
\n See file_result/2 for options to modify the output.\n
\n The use of this predicate is only meaningful if the module has \n previously been instrumented and compiled \n using instrument:instrument/1,2, and the code has been \n run in order to obtain instrumentation results.\n
\n See struct(itemplate) for documentation of how the \n result instrumentation is used in the annotation and pretty-printing \n of the code.\n
\n The predicate is a tool and the instrumentation results of a \n file in an alternate module to the current calling module context \n can be obtained invoking file_result(File)@Module.\n
")]). :- comment(file_result / 2, [summary : "Pretty-print a file, including any instrumentation results", amode : file_result(+, +), args : ["File" : "Atom or string", "OptionList" : "List of options"], see_also : [instrument / 2, instrument / 3, file_result / 1, library(instrument), library(pretty_printer), module_result / 0, module_result / 1, struct(itemplate), defined_modules / 2], desc : html("
\n This will pretty-print the specified source file in the calling \n module context, annotated with the result of instrumentation. \n The resulting .html file is placed in a sub-directory called \n instrument', relative to File.\n
\n The use of this predicate is only meaningful if the module has \n previously been instrumented and compiled \n using instrument:instrument/1,2, and the code has been \n run in order to obtain instrumentation results.\n
\n OptionList is a list of options identical to the one accepted by \n pretty_print/2 in the library(pretty_printer), and can be \n used to modify the output style and the location of the output file.\n
\n Additionally, OptionList may contain the following options:\n
\n This option should only be specified if it was also specified \n during instrumentation (i.e. when using \n instrument:instrument/3).\n
\n See struct(itemplate) for documentation of how the \n result instrumentation is used in the annotation and pretty-printing \n of the code.\n
\n The predicate is a tool and the instrumentation results of a \n file in an alternate module to the current calling module context \n can be obtained invoking module_result(File, OptionList)@Module.\n
")]). :- comment(get_callsite_data / 2, [summary : "Retrieve data associated with an instrumentation callsite \n from its non-logical store.", args : ["SiteId" : "Integer", "UserData" : "Valid Prolog term"], amode : get_callsite_data(+, ?), fail_if : "Data has not been stored for callsite identifier SiteId.", resat : no, exceptions : [4 : "SiteId is not instantiated.", 5 : "SiteId is not an integer."], see_also : [file_callsites / 3, instrument / 2, instrument / 3, library(instrument), module_callsites / 2, set_callsite_data / 2, struct(itemplate), defined_modules / 2], desc : html("\n Each code instrumentation point within a file is uniquely identified \n by its callsite identifier. The callsite identifier is a monotonically \n increasing integer incrementing from the initial value of 0 for a new \n module. \n
\n The predicate retrieves the data (a valid Prolog term) that has been \n associated with the specified instrumentation callsite within a module \n or file.\n
\n The data is stored in a non-logical store and can be stored using \n instrument:set_callsite_data/2.\n
\n The predicate is a tool and data for a callsite of a module other than \n the current calling module context can be retrieved by invoking \n get_callsite_data(SiteId, UserData)@Module.")]). :- comment(instrument / 2, [summary : "Compile a file, inserting predicate instrumentation", args : ["File" : "Atom or string", "ITemplates" : "itemplate, List of itemplate or PredSpec"], amode : instrument(+, +), exceptions : [4 : "ITemplates is not instantiated.", 5 : "ITemplates is not of the appropriate type."], see_also : [erase_all_templates / 0, file_result / 1, file_result / 2, file_callsites / 3, get_callsite_data / 2, instrument / 3, instrument_control / 2, library(instrument), module_callsites / 2, module_result / 0, module_result / 1, set_callsite_data / 2, defined_modules / 2], desc : html("
\n This is a variant of the ECLiPSe compiler that inserts user specified \n instrumentation predicates into the compiled code. This code can then \n be run, and the results analysed by printing them using \n instrument:module_result/0 or instrument:file_result/1.\n
\n ITemplates can be specified as:\n
[itemplate{...} | PredSpec = itemplate{...} ... \n PredSpec = itemplate{...}]\n The itemplate at the head of the list is specifies the global \n template and is optional. The remaining elements of the list are \n itemplate specifying instrumentation for the PredSpec with which \n they are associated.\n \n In addition to supplying the global template, an exclude list of \n PredSpec for predicates that should not be instrumented by the global \n template can be specified:\n
itemplate{...} - \n predicate/1, my_module:my_predicate/8,...]")]).
:- comment(instrument / 3, [summary : "Compile a file, inserting predicate instrumentation", args : ["File" : "Atom or string", "ITemplates" : "itemplate, List of itemplate or PredSpec", "OptionList" : "List of Name:Value pairs"], amode : instrument(+, +, +), exceptions : [4 : "ITemplates is not instantiated.", 5 : "ITemplates is not of the appropriate type."], see_also : [erase_all_templates / 0, file_result / 1, file_result / 2, file_callsites / 3, get_callsite_data / 2, instrument / 3, instrument_control / 2, library(instrument), module_callsites / 2, module_result / 0, module_result / 1, set_callsite_data / 2, defined_modules / 2], desc : html("\n This is a variant of the ECLiPSe compiler that inserts user specified \n instrumentation predicates into the compiled code. \n This code can then be run, and the results analysed by printing them using \n instrument:module_result/0 or instrument:file_result/1.\n
\n ITemplates can be specified as:\n
[itemplate{...} | PredSpec = itemplate{...} ... \n PredSpec = itemplate{...}]\n The itemplate at the head of the list is specifies the global \n template and is optional. The remaining elements of the list are \n itemplate specifying instrumentation for the PredSpec with which \n they are associated.\n \n In addition to supplying the global template, an exclude list of PredSpec \n for predicates that should not be instrumented by the global template can \n be specified:
itemplate{...} - predicate/1, \n my_module:my_predicate/8,...]\n \n OptionList may contain the following options:\n
")]). :- comment(instrument_control / 2, [summary : "Insert or remove instrumentation predicates dynamically \n at runtime.", args : ["Mode" : "Atom", "InstrumentPredSpec" : "PredSpec"], amode : instrument_control(+, +), fail_if : "InstrumentPredSpec is not a predicate specification.", resat : no, exceptions : [68 : "PredSpec is an undefined procedure."], see_also : [instrument / 2, instrument / 3, library(instrument), struct(itemplate)], desc : html("
\n If the asserted option of an itemplate \n is set to one of on, off or \n post_compile then the template's instrumentation \n predicates may be inserted and removed dynamically at runtime.\n
\n When Mode is on the instrumentation predicate \n represented is PredSpec is inserted into the code at the \n positions specified during instrumentation. This is done \n efficiently with negligible runtime overhead. When Mode is \n off the instrumentation predicate is removed from \n the instrumented code.\n
\n If PredSpec is module qualified, the instrumentation predicate \n defined in the context of the module is inserted / removed. If \n unqualified the predicate is assumed to be defined in the context \n of the calling module scope.\n
\n The predicate is a tool and an unqualified instrumentation \n predicate defined in a module other than the current \n calling module context can be inserted / removed by invoking \n instrument_control(Mode, InstrumentPredSpec)@Module.")]). :- comment(module_callsites / 2, [summary : "Retrieve module start and end callsite identifiers.", args : ["StartId" : "Intger", "EndId" : "Integer"], amode : module_callsites(?, ?), fail_if : "StartId or EndId are not the module's starting and \n ending callsite identifiers.", resat : no, see_also : [get_callsite_data / 2, file_callsites / 3, instrument / 2, instrument / 3, library(instrument), set_callsite_data / 2, struct(itemplate), defined_modules / 2], desc : html("
\n Each code instrumentation point within a module is \n uniquely identified by its callsite identifier.\n The callsite identifier is a monotonically increasing \n integer incrementing from the initial value of 0.\n The predicate retrieves the start and end callsite \n identifiers.\n
\n The predicate is a tool and the callsite identifiers \n of a module other than the current calling module \n context can be retrieved by invoking \n module_callsites(StartId, EndId)@Module.")]). :- comment(module_result / 0, [summary : "Pretty-print all files in a module, including any \n instrumentation results", args : [], see_also : [instrument / 2, instrument / 3, file_result / 1, file_result / 2, library(instrument), library(pretty_printer), module_result / 1, struct(itemplate), defined_modules / 2], desc : html("
\n This will pretty-print all source files in the calling module context, \n annotated with the result of instrumentation. The resulting .html \n files are placed in a sub-directory called instrument', relative to \n the files that were compiled into the file.\n
\n See module_result/1 for options to modify the output.\n
\n The use of this predicate is only meaningful if the module has \n previously been instrumented and compiled \n using instrument:instrument/1,2, and the code has been \n run in order to obtain instrumentation results.\n
\n See struct(itemplate) for documentation of how the \n result instrumentation is used in the annotation and pretty-printing \n of the code.\n
\n The predicate is a tool and the instrumentation results of a \n module other than the current calling module context can be obtained \n by invoking module_result@Module.\n
")]). :- comment(module_result / 1, [summary : "Pretty-print all files in a module, including any \n instrumentation results", amode : module_result(+), args : ["OptionList" : "List of options"], see_also : [instrument / 2, instrument / 3, file_result / 1, file_result / 2, library(instrument), library(pretty_printer), module_result / 0, struct(itemplate), defined_modules / 2], desc : html("
\n This will pretty-print all source files in the calling\n module context, annotated with the result of instrumentation. \n The resulting .html files are placed in a sub-directory called \n instrument', relative to the files that were compiled into the file.\n
\n OptionList is a list of options identical to the one accepted by \n pretty_print/2 in the library(pretty_printer), and can be \n used to modify the output style and the location of the output file.\n
\n Additionally, OptionList may contain the following options:\n
\n This option should only be specified if it was also specified \n during instrumentation (i.e. when using \n instrument:instrument/3).\n
\n
\n The use of this predicate is only meaningful if the module has \n previously been instrumented and compiled \n using instrument:instrument/1,2, and the code has been \n run in order to obtain instrumentation results.\n
\n See struct(itemplate) for documentation of how the \n result instrumentation is used in the annotation and pretty-printing \n of the code.\n
\n The predicate is a tool and the instrumentation results of a \n module other than the current calling module context can be obtained \n by invoking module_result(OptionList)@Module.\n
")]). :- comment(set_callsite_data / 2, [summary : "Associate arbitrary data with an instrumentation callsite \n in a non-logical store.", args : ["SiteId" : "Integer", "UserData" : "Valid Prolog term"], amode : set_callsite_data(+, ?), fail_if : no, resat : no, exceptions : [4 : "SiteId is not instantiated.", 5 : "SiteId is not an integer."], see_also : [file_callsites / 3, get_callsite_data / 2, instrument / 2, instrument / 3, library(instrument), module_callsites / 2, struct(itemplate), defined_modules / 2], desc : html("
\n Each code instrumentation point within a file is \n uniquely identified by its callsite identifier.\n The callsite identifier is a monotonically increasing \n integer incrementing from the initial value of 0 for a \n new module. \n
\n The predicate associates arbitrary data (a valid Prolog term) \n with a specified instrumentation callsite within a module or \n file.\n
\n The data is stored in a non-logical store and can be \n retrieved using instrument:get_callsite_data/2.\n
\n The predicate is a tool and data for a callsite \n of a module other than the current calling module context \n can be stored by invoking \n set_callsite_data(SiteId, UserData)@Module.")]). :- comment(get_callsite_data_body / 3, hidden). :- comment(set_callsite_data_body / 3, hidden). :- comment(file_callsites_body / 4, hidden). :- comment(module_callsites_body / 3, hidden). :- comment(instrument_control_body / 3, hidden). :- comment(file_result_body / 3, hidden). :- comment(file_result_body / 2, hidden). :- comment(module_result_body / 2, hidden). :- comment(module_result_body / 1, hidden). :- comment(instrument_body_check_options / 4, hidden). :- comment(instrument_body / 3, hidden). :- comment(erase_file_templates / 2, hidden). :- comment(erase_module_templates / 1, hidden).